habiticafandomcom-20200222-history
Application Programming Interface
Habitica's Application Programming Interface (API) allows programmers to create third-party applications, extensions, and other tools that interface with Habitica. With the user credentials on the API Options tab, the software can gain limited access to a user's Habitica account, allowing them to display and potentially change the user's data and preferences. Version 4 of the API (do not use) Habitica's staff are creating version 4 of Habitica's API but it is still in development, incomplete, and is not suitable for use in any third-party tools. Its behavior may change at any time without notice. Any tools that use it will stop working when it changes. Version 3 of the API is the only version that should be used in third-party tools. In the Habitica V3 API Documentation you will see some entries for version 4. Ignore them. Version 3 of the API On 21 May 2016, version 3 of Habitica's API was released. All third-party software should use it. Versions 1 and 2 of the API have been turned off and cannot be used. The following resources exist to help you update any tools you have written or create new ones: *Habitica V3 API Documentation *Guidance for Comrades page containing helpful and important information that you should read before creating third-party software *Aspiring Comrades guild for asking questions and seeking help Errors in the API Documentation If you find an error in the API documentation, including typos or misleading text, please report it in the Report a Bug guild. If you're not sure if it's an error or not, you can ask in the Aspiring Comrades guild. Using the API To use the API, you send HTTPS requests to Habitica's server. The request's URL defines the type of information you want to fetch or the type of update you want to make. The supported URLs are listed in the API's documentation. Many of the URLs contain variables to further specify the data to fetch or update (e.g., to specify a particular task to modify). * Variable names are prefixed with a colon as in :variableName. The entire string, colon and all, should be replaced. For example, the Group - Get group route is https://habitica.com/api/v3/groups/:groupId and so for the group with the ID 12345678-90ab-40a4-cdef-1234567890ab, you would use https://habitica.com/api/v3/groups/12345678-90ab-40a4-cdef-1234567890ab * Some routes have more than one variable and all must be replaced, for example User - Hatch a pet is https://habitica.com/api/v3/user/hatch/:egg/:hatchingPotion * When variables refer to content types, you can find the appropriate values from the Content - Get all available content objects route (https://habitica.com/api/v3/content). For example, :egg could be TigerCub and :hatchingPotion could be CottonCandyBlue Most of the API routes require a User ID and API Token for authentication, which you always add to the HTTP headers of the request (do not try specifying them in any other way) using the header keys x-api-user and x-api-key for your User ID and API token respectively (see below for examples). If you will be using the API route in a script or other tool, or using it multiple times on the command line, you must also use an x-client header key. As described in the "X-Client Header" section in Guidance for Comrades, the value of that key should be your User ID and the name of your tool. If you haven't yet created a full tool but are just experimenting with the API, you can use a word like "Testing" instead of the name of your tool. It is important that you read Guidance for Comrades to learn more about using the X-Client header correctly. How you add the x-api-user, x-api-key, and x-client headers to your API call depends on how you are making the requests. For shell scripts, you might choose to use the curl command-line tool to send the HTTPS requests. If so, you would format the URL and authentication headers like this: curl https://habitica.com/api/v3/user -s -X GET --compressed \ -H "Content-Type:application/json" \ -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" \ -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" \ -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing" For JavaScript using a jQuery Ajax request, you could use code similar to this: $.ajax({ url: 'https://habitica.com/api/v3/user', type: 'GET', dataType: 'json', cache: false, beforeSend: function(xhr){ xhr.setRequestHeader('x-api-user', '12345678-90ab-416b-cdef-1234567890ab'); xhr.setRequestHeader('x-api-key', '12345678-90ab-416b-cdef-1234567890ab'); xhr.setRequestHeader('x-client', '12345678-90ab-416b-cdef-1234567890ab-MyHabiticaApp'); }, success: yourFunctionToProcessTheData, error: yourFunctionToReportAnError, }); If you are allowing your script or tool to be used by other players, you will want to insert the x-api-user and x-api-key values into your API calls with variables that contain the User ID and API Token of the player who is using your tool. It is important to note that the x-client header should not contain the User ID of that player - it should always be your own User ID because you are the author of the tool. Refer to the "X-Client Header" section in Guidance for Comrades for more information about this, including sample code that uses variables. Each API route uses one of the HTTP request methods, such as GET, POST, PUT, or DELETE, indicated by colored labels in the documentation. It's important to use the correct method in your code (e.g., see the type: 'GET' examples above). The different request methods use different mechanisms for specifying the variables and their values: For GET requests, specify them in the query string. For example, https://habitica.com/api/v3/groups?type=party,guilds For POST, PUT, and DELETE requests, specify information in body parameters. The method for doing this depends on how you are making the requests. For HTML forms, use form fields such as input and textarea. jQuery provides a jQuery.post() method. For curl, use the -d option: curl -X POST -d "type=todo&text=New Task Text&notes=Some Notes" \ -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" \ -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" \ -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing" \ https://habitica.com/api/v3/tasks/user curl -X PUT -d "text=Edited Task Text" \ -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" \ -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" \ -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing" \ https://habitica.com/api/v3/tasks/7d4a623d-0a2c-48e2-b9d9-feea1fa2d467 curl -X DELETE -d "password=yourPasswordGoesHere" \ -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" \ -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" \ -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing" \ https://habitica.com/api/v3/user When data needs to be specified in an array or an object, use constructors with { ... } and [ ... ] such as in this example that creates a To-Do with two tags and a checklist containing two items: curl -X POST \ -d '{ "type": "todo", "text": "task title", "tags": [ "12345678-90ab-416b-cdef-1234567890ab", "abcdef12-90ab-416b-cdef-1234567890ab" ], "checklist": [ { "text": "1st checklist item", "completed": false }, { "text": "2nd checklist item", "completed": false } ], "collapseChecklist": true }' \ -H "Content-Type: application/json" \ -H "x-api-user: 12345678-90ab-416b-cdef-1234567890ab" \ -H "x-api-key: 12345678-90ab-416b-cdef-1234567890ab" \ -H "x-client: 12345678-90ab-416b-cdef-1234567890ab-Testing" \ https://habitica.com/api/v3/tasks/user Tips To find your number of Gems, use the /api/v3/user GET route and then find the data.balance value. Multiply it by 4 to get the number of gems. The balance is the US dollar equivalent of the number of Gems, where $1 is 4 Gems. The Extensions, Add-Ons, and Customizations page has some tools that make using the API easier. They are listed in the "Current Apps and Extensions" table with "API" in the "Type" column. Version 2 of the API The information in this section pertains to version 2 of the API, which has been turned off and cannot be used. This information remains here only as a reference to assist you in upgrading existing tools to version 3 of the API. Extensions and scripts could use Habitica's up/down scoring system for individual tasks. An example of an extension that leveraged this is the Chrome Extension, which up-scored you for visiting productive websites and down-scored you for visiting procrastination-related websites. Other examples of extensions and scripts that up-scored you for good behavior and down-scored you for bad behavior include various Pomodoro-related tools, the Anki Extension, and GitHabit. For extensions and scripts, Habitica had a simple API for up-scoring and down-scoring third-party Habits. Programmers should have issued an HTTP POST to: /api/v2/user/tasks/{id}/{direction} * {id} is a unique identifier for a task consisting of lowercase letters. Try to make it something simple and straightforward, like 'productivity' or 'fitness', because other services may piggy-back off your task. For example, the Chrome extension down-scores a 'productivity' task when you visit vice-related websites (reddit, 9gag, etc). However, Pomodoro up-scores 'productivity' when you complete a task. So the two services share a single task to score your overall productivity. If the task doesn't yet exist, it is created the first time you POST to this URL. * {direction} is 'up' or 'down' * A POST body consisting of the API token is required For example, this applescript command coupled with a timer can record a + on a habit at regular intervals. Replace xxxxx with your User ID and API key. Change 'productivity' to whatever you want to call your habit. do shell script "curl -X POST --compressed -H 'Content-Type:application/json' -H 'x-api-user: xxxxx' -H 'x-api-key: xxxxx' https://habitica.com/api/v2/user/tasks/'productivity'/up" Version 1 of the API Version 1 of the API has been turned off and cannot be used. fr:Application Programming Interface ru:Программный интерфейс приложения Category:Contributing Category:Extensions, Add-Ons, and Customizations